<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="idle.html" />
<link rel="prev" href="module-ScrolledText.html" />
<link rel="parent" href="tkinter.html" />
<link rel="next" href="pen-rawpen-objects.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>20.4 turtle -- Turtle graphics for Tk</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="20.3 scrolledtext  "
  href="module-ScrolledText.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="20. graphical User Interfaces"
  href="tkinter.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="20.4.1 Turtle, pen and"
  href="pen-rawpen-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-ScrolledText.html">20.3 ScrolledText  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="tkinter.html">20. Graphical User Interfaces</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pen-rawpen-objects.html">20.4.1 Turtle, Pen and</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h1><a name="SECTION0022400000000000000000">
20.4 <tt class="module">turtle</tt> --
         Turtle graphics for Tk</a>
</h1>

<p>
<a name="module-turtle"></a>   
<p class="availability">Availability: <span
 class="platform">Tk</span>.</p>

<p>

<p>
The <tt class="module">turtle</tt> module provides turtle graphics primitives, in both an
object-oriented and procedure-oriented ways. Because it uses <tt class="module">Tkinter</tt>
for the underlying graphics, it needs a version of python installed with
Tk support.

<p>
The procedural interface uses a pen and a canvas which are automagically
created when any of the functions are called.

<p>
The <tt class="module">turtle</tt> module defines the following functions:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4751' xml:id='l2h-4751' class="function">degrees</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Set angle measurement units to degrees.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4752' xml:id='l2h-4752' class="function">radians</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Set angle measurement units to radians.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4753' xml:id='l2h-4753' class="function">setup</tt></b>(</nobr></td>
  <td><var>**kwargs</var>)</td></tr></table></dt>
<dd>
Sets the size and position of the main window.  Keywords are:

<ul>
<li><code>width</code>: either a size in pixels or a fraction of the screen.
   The default is 50% of the screen.
</li>
<li><code>height</code>: either a size in pixels or a fraction of the screen.
   The default is 50% of the screen.
</li>
<li><code>startx</code>: starting position in pixels from the left edge
      of the screen. <code>None</code> is the default value and 
      centers the window horizontally on screen.
</li>
<li><code>starty</code>: starting position in pixels from the top edge
      of the screen. <code>None</code> is the default value and 
      centers the window vertically on screen.
</li>
</ul>

<p>
Examples:

<p>
<div class="verbatim"><pre>
# Uses default geometry: 50% x 50% of screen, centered.
setup()  

# Sets window to 200x200 pixels, in upper left of screen
setup (width=200, height=200, startx=0, starty=0)

# Sets window to 75% of screen by 50% of screen, and centers it.
setup(width=.75, height=0.5, startx=None, starty=None)
</pre></div>

<p>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4754' xml:id='l2h-4754' class="function">title</tt></b>(</nobr></td>
  <td><var>title_str</var>)</td></tr></table></dt>
<dd>
Set the window's title to <var>title</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4755' xml:id='l2h-4755' class="function">done</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Enters the Tk main loop.  The window will continue to 
be displayed until the user closes it or the process is killed.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4756' xml:id='l2h-4756' class="function">reset</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Clear the screen, re-center the pen, and set variables to the default
values.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4757' xml:id='l2h-4757' class="function">clear</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Clear the screen.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4758' xml:id='l2h-4758' class="function">tracer</tt></b>(</nobr></td>
  <td><var>flag</var>)</td></tr></table></dt>
<dd>
Set tracing on/off (according to whether flag is true or not). Tracing
means line are drawn more slowly, with an animation of an arrow along the 
line.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4759' xml:id='l2h-4759' class="function">speed</tt></b>(</nobr></td>
  <td><var>speed</var>)</td></tr></table></dt>
<dd>
Set the speed of the turtle. Valid values for the parameter
<var>speed</var> are <code>'fastest'</code> (no delay), <code>'fast'</code>,
(delay 5ms), <code>'normal'</code> (delay 10ms), <code>'slow'</code>
(delay 15ms), and <code>'slowest'</code> (delay 20ms).

<span class="versionnote">New in version 2.5.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4760' xml:id='l2h-4760' class="function">delay</tt></b>(</nobr></td>
  <td><var>delay</var>)</td></tr></table></dt>
<dd>
Set the speed of the turtle to <var>delay</var>, which is given
in ms. 
<span class="versionnote">New in version 2.5.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4761' xml:id='l2h-4761' class="function">forward</tt></b>(</nobr></td>
  <td><var>distance</var>)</td></tr></table></dt>
<dd>
Go forward <var>distance</var> steps.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4762' xml:id='l2h-4762' class="function">backward</tt></b>(</nobr></td>
  <td><var>distance</var>)</td></tr></table></dt>
<dd>
Go backward <var>distance</var> steps.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4763' xml:id='l2h-4763' class="function">left</tt></b>(</nobr></td>
  <td><var>angle</var>)</td></tr></table></dt>
<dd>
Turn left <var>angle</var> units. Units are by default degrees, but can be
set via the <tt class="function">degrees()</tt> and <tt class="function">radians()</tt> functions.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4764' xml:id='l2h-4764' class="function">right</tt></b>(</nobr></td>
  <td><var>angle</var>)</td></tr></table></dt>
<dd>
Turn right <var>angle</var> units. Units are by default degrees, but can be
set via the <tt class="function">degrees()</tt> and <tt class="function">radians()</tt> functions.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4765' xml:id='l2h-4765' class="function">up</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Move the pen up -- stop drawing.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4766' xml:id='l2h-4766' class="function">down</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Move the pen down -- draw when moving.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4767' xml:id='l2h-4767' class="function">width</tt></b>(</nobr></td>
  <td><var>width</var>)</td></tr></table></dt>
<dd>
Set the line width to <var>width</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4768' xml:id='l2h-4768' class="function">color</tt></b>(</nobr></td>
  <td><var>s</var>)</td></tr></table></dt>
<dd>
<dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt class="function">color</tt></b>(</nobr></td>
  <td><var>(r, g, b)</var>)</td></tr></table></dt>
<dd><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt class="function">color</tt></b>(</nobr></td>
  <td><var>r, g, b</var>)</td></tr></table></dt>
<dd>Set the pen color.  In the first form, the color is specified as a
Tk color specification as a string.  The second form specifies the
color as a tuple of the RGB values, each in the range [0..1].  For the
third form, the color is specified giving the RGB values as three
separate parameters (each in the range [0..1]).
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4769' xml:id='l2h-4769' class="function">write</tt></b>(</nobr></td>
  <td><var>text</var><big>[</big><var>, move</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Write <var>text</var> at the current pen position. If <var>move</var> is true,
the pen is moved to the bottom-right corner of the text. By default,
<var>move</var> is false.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4770' xml:id='l2h-4770' class="function">fill</tt></b>(</nobr></td>
  <td><var>flag</var>)</td></tr></table></dt>
<dd>
The complete specifications are rather complex, but the recommended 
usage is: call <code>fill(1)</code> before drawing a path you want to fill,
and call <code>fill(0)</code> when you finish to draw the path.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4771' xml:id='l2h-4771' class="function">begin_fill</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Switch turtle into filling mode; 
Must eventually be followed by a corresponding end_fill() call.
Otherwise it will be ignored.

<span class="versionnote">New in version 2.5.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4772' xml:id='l2h-4772' class="function">end_fill</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
End filling mode, and fill the shape; equivalent to <code>fill(0)</code>.

<span class="versionnote">New in version 2.5.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4773' xml:id='l2h-4773' class="function">circle</tt></b>(</nobr></td>
  <td><var>radius</var><big>[</big><var>, extent</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Draw a circle with radius <var>radius</var> whose center-point is
<var>radius</var> units left of the turtle.
<var>extent</var> determines which part of a circle is drawn: if
not given it defaults to a full circle.

<p>
If <var>extent</var> is not a full circle, one endpoint of the arc is the
current pen position. The arc is drawn in a counter clockwise
direction if <var>radius</var> is positive, otherwise in a clockwise
direction.  In the process, the direction of the turtle is changed
by the amount of the <var>extent</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4774' xml:id='l2h-4774' class="function">goto</tt></b>(</nobr></td>
  <td><var>x, y</var>)</td></tr></table></dt>
<dd>
<dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt class="function">goto</tt></b>(</nobr></td>
  <td><var>(x, y)</var>)</td></tr></table></dt>
<dd>Go to co-ordinates <var>x</var>, <var>y</var>.  The co-ordinates may be
specified either as two separate arguments or as a 2-tuple.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4775' xml:id='l2h-4775' class="function">towards</tt></b>(</nobr></td>
  <td><var>x, y</var>)</td></tr></table></dt>
<dd>
Return the angle of the line from the turtle's position
to the point <var>x</var>, <var>y</var>. The co-ordinates may be
specified either as two separate arguments, as a 2-tuple,
or as another pen object.

<span class="versionnote">New in version 2.5.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4776' xml:id='l2h-4776' class="function">heading</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the current orientation of the turtle.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4777' xml:id='l2h-4777' class="function">setheading</tt></b>(</nobr></td>
  <td><var>angle</var>)</td></tr></table></dt>
<dd>
Set the orientation of the turtle to <var>angle</var>.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4778' xml:id='l2h-4778' class="function">position</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the current location of the turtle as an <code>(x,y)</code> pair.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4779' xml:id='l2h-4779' class="function">setx</tt></b>(</nobr></td>
  <td><var>x</var>)</td></tr></table></dt>
<dd>
Set the x coordinate of the turtle to <var>x</var>.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4780' xml:id='l2h-4780' class="function">sety</tt></b>(</nobr></td>
  <td><var>y</var>)</td></tr></table></dt>
<dd>
Set the y coordinate of the turtle to <var>y</var>.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4781' xml:id='l2h-4781' class="function">window_width</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the width of the canvas window.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4782' xml:id='l2h-4782' class="function">window_height</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the height of the canvas window.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
This module also does <code>from math import *</code>, so see the
documentation for the <tt class="module"><a href="module-math.html">math</a></tt> module for additional constants
and functions useful for turtle graphics.

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4783' xml:id='l2h-4783' class="function">demo</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Exercise the module a bit.
</dl>

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4784' xml:id='l2h-4784' class="exception">Error</tt></b></dt>
<dd>
Exception raised on any error caught by this module.
</dd></dl>

<p>
For examples, see the code of the <tt class="function">demo()</tt> function.

<p>
This module defines the following classes:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-4785' xml:id='l2h-4785' class="class">Pen</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Define a pen. All above functions can be called as a methods on the given
pen. The constructor automatically creates a canvas do be drawn on.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-4786' xml:id='l2h-4786' class="class">Turtle</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Define a pen. This is essentially a synonym for <code>Pen()</code>;
<tt class="class">Turtle</tt> is an empty subclass of <tt class="class">Pen</tt>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-4787' xml:id='l2h-4787' class="class">RawPen</tt></b>(</nobr></td>
  <td><var>canvas</var>)</td></tr></table></dt>
<dd>
Define a pen which draws on a canvas <var>canvas</var>. This is useful if 
you want to use the module to create graphics in a ``real'' program.
</dl>

<p>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<a name="CHILD_LINKS"><strong>Subsections</strong></a>

<ul class="ChildLinks">
<li><a href="pen-rawpen-objects.html">20.4.1 Turtle, Pen and RawPen Objects</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="20.3 scrolledtext  "
  href="module-ScrolledText.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="20. graphical User Interfaces"
  href="tkinter.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="20.4.1 Turtle, pen and"
  href="pen-rawpen-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-ScrolledText.html">20.3 ScrolledText  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="tkinter.html">20. Graphical User Interfaces</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pen-rawpen-objects.html">20.4.1 Turtle, Pen and</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
